home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 January / macformat-020.iso / Shareware City / Applications / Alpha.5.96 folder / Help / BibTeX Help < prev    next >
Encoding:
Text File  |  1994-09-19  |  8.8 KB  |  230 lines  |  [TEXT/ALFA]
  1. ----------------------
  2. BibTeX mode for Alpha
  3. ----------------------
  4.  
  5. This document describes features of Bib mode and the BibTeX menu, 
  6. which were written to simplify the use and maintenance of BibTeX 
  7. citation database files.
  8.  
  9. Bib Mode and the BibTeX menu
  10. ----------------------------
  11.  
  12. Bib mode is entered when you open a file with a '.bib' suffix, or select 
  13. the mode explicitly from the modes menu.  In Bib mode,
  14.  
  15. 1.  A BibTeX menu is added to the menubar.  From this menu, you can:
  16.     (key bindings indicated where available)
  17.  
  18.  •    Launch the BibTeX application.
  19.  
  20.  •    Insert templates for any of the various BibTeX bibliography entry 
  21.     types or data fields.
  22.     
  23.     By default, only the required fields an the entry are included in 
  24.     the template.  This can be customized as described below.
  25.    
  26.  •    Select (highlight) the current entry (in which the cursor sits), 
  27.     allowing the entry to be easily moved, copied or deleted.
  28.     (Ctl-Shift-B)
  29.    
  30.  •    Jump to the next or previous entry.
  31.      (Ctl-Shift-N or Ctl-Shift-P)
  32.    
  33.  •    Reformat the current entry in a standard form, with data fields 
  34.     indented and aligned, and data-field delimiters made uniform.
  35.     (Ctl-Shift-L)
  36.    
  37.     The data field indentation is controlled by the "indentString" mode 
  38.     variable in the mode-flags menu.  The "fieldBraces" flag selects curly 
  39.     braces or double-quotes as the data-field delimiter; likewise, the 
  40.     "entryBraces" flag selects curly braces or parentheses as the 
  41.     data-field delimiter.  The "fillColumn" variable controls line-wrapping.
  42.    
  43.  •    Search for entries that match a given regular expression.
  44.      (Ctl-Shift-M)
  45.    
  46.  •    Search for entries in which a particular field matches a regular 
  47.     expression.
  48.     (Ctl-Shift-F)
  49.  
  50.     Entries found in a search will be copied to a new window (the 
  51.     default) or back into the original buffer, replacing the previous 
  52.     contents of the buffer; this is controlled by the "overwriteBuffer" 
  53.     flag in the mode-flags menu.  The contents of a ".bib" file, 
  54.     however, will never be overwritten by a search, since entries are 
  55.     typically lost.
  56.     
  57.  •    Sort the database by cite-key, by first author, or by last author.
  58.  
  59.      The overwriteBuffer flag also controls whether the sorted database 
  60.      is written back to the original buffer or into a new one.  A ".bib" 
  61.      file _can_ be overwritten by a sort, since no entries are lost.
  62.        
  63. 2.  Selecting 'Mark File' in the marks menu, on the sidebar, will 
  64.     add a mark for each entry in the bib file using the cite key of the 
  65.     entry.  These are added in order of appearance in the file, but can 
  66.     subsequently be sorted alphabetically using the "Named Marks:Sort" 
  67.     command under the "Search" menu.
  68.  
  69. 3. Key words in Bib files are automatically colorized.
  70.  
  71.  
  72. Key Bindings
  73. ------------
  74.  
  75. Most of these functions (except template insertion) are also bound to 
  76. keystrokes.  The standard bindings are
  77.  
  78.     Ctl-Shift-N     next entry
  79.     Ctl-Shift-P     previous entry
  80.  
  81.     Ctl-Shift-B     select entry   
  82.     Ctl-Shift-L     format entry
  83.  
  84.     Ctl-Shift-M     search entries
  85.     Ctl-Shift-F     search fields
  86.  
  87.             tab     next tab stop      (as in TeX mode)
  88.       Shift-tab     previous tab stop  ( "  "  "   "  )
  89.         Ctl-tab     nth tab stop       ( "  "  "   "  )
  90.         Cmd-tab     clear tab stop     ( "  "  "   "  )
  91.         
  92.         Opt-tab     insert a tab       ( "  "  "   "  )
  93.  
  94. Although the TeX-mode keybindings aren't available in Bib mode, the 
  95. LaTeX menu is left on the menubar.  This may be useful for inserting the
  96. various text-style codes that are recognized in BibTeX fields. 
  97.  
  98.  
  99. Customizing Entry Templates
  100. ---------------------------
  101.  
  102. As mentioned above, by default only the required fields are included 
  103. when a new bib entry is created.  You can select any other set of fields 
  104. by adding an appropriate entry to the 'myFld' array, following the 
  105. example for the Article entry in the file :UserCode:bibtex.tcl file.  
  106. Some day I'll make it easier to customize this, but for now it's 
  107. necessary to modify bibtex.tcl.
  108.  
  109. You should _not_ change the 'rqdFld' or 'optFld' arrays, since these 
  110. will (some day) be used for syntax checking.
  111.  
  112.  
  113. Bugs, etc.
  114. ----------
  115.  
  116. Bug reports, complaints and suggestions are very welcome.  In 
  117. particular, the code hasn't been tested for a wide variety of BibTeX 
  118. data formats, so I don't know how robust my routines for parsing BibTeX 
  119. entries really are.  Some of my own ideas for additional features and/or
  120. improvements are listed further below.  
  121.  
  122. Comments and bug reports should be directed to
  123.  
  124. Tom Pollard
  125.  
  126. e-mail:            pollard@cucbs.chem.columbia.edu
  127.  
  128. snail-mail:        544 W 114th St #2R
  129.                 New York, NY 10025
  130.                 USA
  131.  
  132.  
  133. Version History
  134. ---------------
  135.  
  136. 1.9 (9/94)    'getFields' should now correctly parse any legal entry.
  137.               'language' field now included.
  138.               Default values for new fields (eg 'language') may be defined
  139.               'preferBraces' replaced by 'fieldBraces' and 'entryBraces'.
  140.               line-wrapping is done on reformatted entries.
  141.               '@string' entries preserved in sorts.
  142.               text before first entry and after last entry are preserved
  143.                   by sorts.
  144. 1.8 (8/94)    "getEntry" now recognizes parens as entry delimiters
  145. 1.7 (8/94)    Bug fixes and accomodations to latex.tcl v2.2
  146.               Template insertion streamlined
  147.               Choose multiple fields at a time from a list dialog
  148. 1.6 (8/94)    "preferBraces" allows braces or quotes to be default for
  149.                   new or reformatted entries,
  150.               Menu built using $entryNames and $fieldNames,
  151.               'sortByAuthors' can now sort using last author first,
  152.                   and is a bit faster,
  153.               'formatEntry' rewrites entries in canonical format,
  154.               More customization of canonical format allowed ('indentString')
  155.               Bib mode definition adapted to Alpha 5.90.
  156. 1.5 (7/94)    "sortByAuthors" is now robust,
  157.               Mode of new windows now set correctly.
  158. 1.4 (7/94)    Added sorting by authors, but still only semi-functional,
  159.               Added regexp searching by field,
  160.               "getEntry" bugs fixed.
  161. 1.2 (7/94)    Bib mode definition adapted to Alpha 5.85,
  162.               Added bib-file marking (bibMarkFile),
  163.               Entry and field creation now controlled by data arrays.
  164. 1.1 (6/94)    Custom BibTeX icon, 
  165.               Added simple search capability (matchingEntries).
  166. 1.0 (9/93)    First stable version.
  167.  
  168.  
  169. Possible Future Enhancements
  170. ----------------------------
  171.  
  172. 1.    Sorting by other fields.  Specifically, I'd like to have it
  173.     sort by date, by first author and date, or by last author and date.
  174.     
  175. 2.    Allowing more customization of the 'standard' entry format used for
  176.     new entries and the 'Format Entry' command.   
  177.     
  178. 3.  Allowing the user to interactively choose the standard fields used 
  179.     for a given entry type.
  180.     
  181. 4.    Tighter integration with TeX mode; for instance, automatically 
  182.     opening the .bib files for a document by scanning the '\bibliography{}'
  183.     command(s) in the document, and allowing single-keystroke jumps from a 
  184.     citation ('\cite{}') to the corresponding database entry.  An easy way 
  185.     to paste cite keys into a TeX document might be nice, but I don't know 
  186.     what the most convenient way to do that would be.
  187.     
  188. 5.  Allowing more complicated searches.  Logical 'AND' searches can be 
  189.     done now by doing additional searches on the results of previous ones.  
  190.     It would be nice to allow logical 'OR' searches by concatenating the 
  191.     results of successive searches to a database in the same buffer.  Ideas 
  192.     for simple, intuitive ways to control this would be welcome.
  193.  
  194. 6.    Some sort of consistency and/or syntax checking of the database; for
  195.     instance, verifying that all entries have the required fields and 
  196.     checking for duplicate entries.
  197.  
  198. ?.  Since the code parses BibTeX entries already, it would be easy to 
  199.     export .bib files to other formats, but I'm not sure if it's a good idea 
  200.     to start burdening Alpha with that sort of thing.  Writing Perl scripts 
  201.     for file conversions is probably a better route.  See, for instance, the 
  202.     "CC to BibTeX" Perl script (included in the :Tcl:UserCode:TextFilters 
  203.     folder), which converts citations from the on-line Current Contents 
  204.     database (the one at UC Berkeley, anyway) to BibTeX format.  
  205.  
  206.  
  207. BibTeX application
  208. ------------------
  209.  
  210. If you don't already have a BibTeX application, version 2.0 of MacBibTeX
  211. is available, among other places, from
  212.  
  213.     ftp.bluesky.com    (198.145.40.2)        pub/utilities/BibTeX.sea.hqx
  214.  
  215. It was written by
  216.  
  217.     Jim Studt        <jim@wucs1.wustl.edu>   , and
  218.     Michael Kahn    <kahn@wucs1.wustl.edu>
  219.     
  220. based on Oren Patashnik's original BibTeX 0.99c .
  221.  
  222. Acknowledgments:
  223. ----------------
  224.  
  225. This package was inspired by LaTeX support package (latex.tcl), written by
  226.  
  227.    Richard T. Austin  <austin@eecs.umich.edu>  , and (currently),
  228.    Tom Scavo          <trscavo@syr.edu>
  229.    
  230. ---------------------------------------------------------------------------